home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / u_man / cat3 / Tk / crtmainwin.z / crtmainwin
Encoding:
Text File  |  1998-10-30  |  16.6 KB  |  265 lines
  1.  
  2.  
  3.  
  4. TTTTkkkk____CCCCrrrreeeeaaaatttteeeeMMMMaaaaiiiinnnnWWWWiiiinnnnddddoooowwww((((3333TTTTkkkk))))                              TTTTkkkk____CCCCrrrreeeeaaaatttteeeeMMMMaaaaiiiinnnnWWWWiiiinnnnddddoooowwww((((3333TTTTkkkk))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      Tk_CreateMainWindow, Tk_CreateWindow, Tk_CreateWindowFromPath,
  10.      Tk_DestroyWindow, Tk_MakeWindowExist - create or delete window
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>>
  14.  
  15.      Tk_Window
  16.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeMMMMaaaaiiiinnnnWWWWiiiinnnnddddoooowwww(_i_n_t_e_r_p, _s_c_r_e_e_n_N_a_m_e, _b_a_s_e_N_a_m_e, _c_l_a_s_s_N_a_m_e)
  17.  
  18.      Tk_Window
  19.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeWWWWiiiinnnnddddoooowwww(_i_n_t_e_r_p, _p_a_r_e_n_t, _n_a_m_e, _t_o_p_L_e_v_S_c_r_e_e_n)
  20.  
  21.      Tk_Window
  22.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeWWWWiiiinnnnddddoooowwwwFFFFrrrroooommmmPPPPaaaatttthhhh(_i_n_t_e_r_p, _t_k_w_i_n, _p_a_t_h_N_a_m_e, _t_o_p_L_e_v_S_c_r_e_e_n)
  23.  
  24.      TTTTkkkk____DDDDeeeessssttttrrrrooooyyyyWWWWiiiinnnnddddoooowwww(_t_k_w_i_n)
  25.  
  26.      TTTTkkkk____MMMMaaaakkkkeeeeWWWWiiiinnnnddddoooowwwwEEEExxxxiiiisssstttt(_t_k_w_i_n)
  27.  
  28. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  29.      Tcl_Interp   *_i_n_t_e_r_p         (out)     Tcl interpreter to use for error
  30.                                             reporting.  If no error occurs,
  31.                                             then *_i_n_t_e_r_p isn't modified.  For
  32.                                             TTTTkkkk____CCCCrrrreeeeaaaatttteeeeMMMMaaaaiiiinnnnWWWWiiiinnnnddddoooowwww, this
  33.                                             interpreter is associated
  34.                                             permanently with the created
  35.                                             window, and Tk-related commands
  36.                                             are bound into the interpreter.
  37.  
  38.      char         *_s_c_r_e_e_n_N_a_m_e     (in)      String name of screen on which to
  39.                                             create window.  Has the form
  40.                                             _d_i_s_p_l_a_y_N_a_m_e...._s_c_r_e_e_n_N_u_m, where
  41.                                             _d_i_s_p_l_a_y_N_a_m_e is the name of a
  42.                                             display and _s_c_r_e_e_n_N_u_m is a screen
  43.                                             number.  If the dot and _s_c_r_e_e_n_N_u_m
  44.                                             are omitted, the screen number
  45.                                             defaults to 0.  If _s_c_r_e_e_n_N_a_m_e is
  46.                                             NULL or empty string, defaults to
  47.                                             contents of DISPLAY environment
  48.                                             variable.
  49.  
  50.      char         *_b_a_s_e_N_a_m_e       (in)      Name to use for this main window.
  51.                                             See below for details.
  52.  
  53.      char         *_c_l_a_s_s_N_a_m_e      (in)      Class to use for application and
  54.                                             for main window.
  55.  
  56.      Tk_Window    _p_a_r_e_n_t          (in)      Token for the window that is to
  57.                                             serve as the logical parent of the
  58.                                             new window.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. TTTTkkkk____CCCCrrrreeeeaaaatttteeeeMMMMaaaaiiiinnnnWWWWiiiinnnnddddoooowwww((((3333TTTTkkkk))))                              TTTTkkkk____CCCCrrrreeeeaaaatttteeeeMMMMaaaaiiiinnnnWWWWiiiinnnnddddoooowwww((((3333TTTTkkkk))))
  71.  
  72.  
  73.  
  74.      char         *_n_a_m_e           (in)      Name to use for this window.  Must
  75.                                             be unique among all children of
  76.                                             the same _p_a_r_e_n_t.
  77.  
  78.      char         *_t_o_p_L_e_v_S_c_r_e_e_n   (in)      Has same format as _s_c_r_e_e_n_N_a_m_e.  If
  79.                                             NULL, then new window is created
  80.                                             as an internal window.  If non-
  81.                                             NULL, new window is created as a
  82.                                             top-level window on screen
  83.                                             _t_o_p_L_e_v_S_c_r_e_e_n.  If _t_o_p_L_e_v_S_c_r_e_e_n is
  84.                                             an empty string (``'') then new
  85.                                             window is created as top-level
  86.                                             window of _p_a_r_e_n_t's screen.
  87.  
  88.      Tk_Window    _t_k_w_i_n           (in)      Token for window.
  89.  
  90.      char         *_p_a_t_h_N_a_m_e       (in)      Name of new window, specified as
  91.                                             path name within application (e.g.
  92.                                             ....aaaa....bbbb....cccc).
  93.  
  94.  
  95. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  96.      The three procedures TTTTkkkk____CCCCrrrreeeeaaaatttteeeeMMMMaaaaiiiinnnnWWWWiiiinnnnddddoooowwww, TTTTkkkk____CCCCrrrreeeeaaaatttteeeeWWWWiiiinnnnddddoooowwww, and
  97.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeWWWWiiiinnnnddddoooowwwwFFFFrrrroooommmmPPPPaaaatttthhhh are used to create new windows for use in Tk-
  98.      based applications.  Each of the procedures returns a token that can be
  99.      used to manipulate the window in other calls to the Tk library.  If the
  100.      window couldn't be created successfully, then NULL is returned and
  101.      _i_n_t_e_r_p->_r_e_s_u_l_t is modified to hold an error message.
  102.  
  103.      Tk supports three different kinds of windows:  main windows, internal
  104.      windows, and top-level windows.  A main window is the outermost window
  105.      corresponding to an application.  Main windows correspond to the
  106.      independent units of an application, such as a view on a file that is
  107.      part of an editor, or a clock, or a terminal emulator.  A main window is
  108.      created as a child of the root window of the screen indicated by the
  109.      _s_c_r_e_e_n_N_a_m_e.  Each main window, and all its descendants, are typically
  110.      associated with a single Tcl command interpreter.  An internal window is
  111.      an interior window of a Tk application, such as a scrollbar or menu bar
  112.      or button.  A top-level window is one that is created as a child of a
  113.      screen's root window, rather than as an interior window, but which is
  114.      logically part of some existing main window.  Examples of top-level
  115.      windows are pop-up menus and dialog boxes.
  116.  
  117.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeMMMMaaaaiiiinnnnWWWWiiiinnnnddddoooowwww creates a new main window and associates its _i_n_t_e_r_p
  118.      argument with that window and all its eventual descendants.
  119.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeMMMMaaaaiiiinnnnWWWWiiiinnnnddddoooowwww also carries out several other actions to set up the
  120.      new application.  First, it adds all the Tk commands to those already
  121.      defined for _i_n_t_e_r_p.  Second, it turns the new window into a ttttoooopppplllleeeevvvveeeellll
  122.      widget, which will cause the X window to be created and mapped as soon as
  123.      the application goes idle.  Third, TTTTkkkk____CCCCrrrreeeeaaaatttteeeeMMMMaaaaiiiinnnnWWWWiiiinnnnddddoooowwww registers _i_n_t_e_r_p
  124.      so that it can be accessed remotely by other Tk applications using the
  125.      sssseeeennnndddd command and the name _b_a_s_e_N_a_m_e.  Normally, _b_a_s_e_N_a_m_e consists of the
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. TTTTkkkk____CCCCrrrreeeeaaaatttteeeeMMMMaaaaiiiinnnnWWWWiiiinnnnddddoooowwww((((3333TTTTkkkk))))                              TTTTkkkk____CCCCrrrreeeeaaaatttteeeeMMMMaaaaiiiinnnnWWWWiiiinnnnddddoooowwww((((3333TTTTkkkk))))
  137.  
  138.  
  139.  
  140.      name of the application followed by a space and an identifier for this
  141.      particular main window (if such an identifier is relevant).  For example,
  142.      an editor named mmmmxxxx displaying the file ffffoooooooo....cccc would use ``mx foo.c'' as
  143.      the basename.  An application that doesn't usually have multiple
  144.      instances, such as a clock program, would just use the name of the
  145.      application, e.g. ``xclock''.  If _b_a_s_e_N_a_m_e is already in use by some
  146.      other registered interpreter, then TTTTkkkk____CCCCrrrreeeeaaaatttteeeeMMMMaaaaiiiinnnnWWWWiiiinnnnddddoooowwww extends _b_a_s_e_N_a_m_e
  147.      with a number to produce a unique name like ``mx foo.c #2'' or ``xclock
  148.      #12''.  This name is used both as the name of the window (returned by
  149.      TTTTkkkk____NNNNaaaammmmeeee) and as the registered name of the interpreter.  Fourth,
  150.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeMMMMaaaaiiiinnnnWWWWiiiinnnnddddoooowwww sets _c_l_a_s_s_N_a_m_e as the class of the application (among
  151.      other things, this is used for lookups in the option database), and also
  152.      as the class of the main widget.
  153.  
  154.      Either internal or top-level windows may be created by calling
  155.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeWWWWiiiinnnnddddoooowwww.  If the _t_o_p_L_e_v_S_c_r_e_e_n argument is NULL, then the new
  156.      window will be an internal window.  If _t_o_p_L_e_v_S_c_r_e_e_n is non-NULL, then the
  157.      new window will be a top-level window: _t_o_p_L_e_v_S_c_r_e_e_n indicates the name of
  158.      a screen and the new window will be created as a child of the root window
  159.      of _t_o_p_L_e_v_S_c_r_e_e_n.  In either case Tk will consider the new window to be
  160.      the logical child of _p_a_r_e_n_t:  the new window's path name will reflect
  161.      this fact, options may be specified for the new window under this
  162.      assumption, and so on.  The only difference is that new X window for a
  163.      top-level window will not be a child of _p_a_r_e_n_t's X window.  For example,
  164.      a pull-down menu's _p_a_r_e_n_t would be the button-like window used to invoke
  165.      it, which would in turn be a child of the menu bar window.  A dialog box
  166.      might have the application's main window as its parent.  This approach
  167.      means that all the windows of an application fall into a hierarchical
  168.      arrangement with a single logical root:  the application's main window.
  169.  
  170.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeWWWWiiiinnnnddddoooowwwwFFFFrrrroooommmmPPPPaaaatttthhhh offers an alternate way of specifying new
  171.      windows.  In TTTTkkkk____CCCCrrrreeeeaaaatttteeeeWWWWiiiinnnnddddoooowwwwFFFFrrrroooommmmPPPPaaaatttthhhh the new window is specified with a
  172.      token for any window in the target application (_t_k_w_i_n), plus a path name
  173.      for the new window.  It produces the same effect as TTTTkkkk____CCCCrrrreeeeaaaatttteeeeWWWWiiiinnnnddddoooowwww and
  174.      allows both top-level and internal windows to be created, depending on
  175.      the value of _t_o_p_L_e_v_S_c_r_e_e_n.  In calls to TTTTkkkk____CCCCrrrreeeeaaaatttteeeeWWWWiiiinnnnddddoooowwwwFFFFrrrroooommmmPPPPaaaatttthhhh, as in
  176.      calls to TTTTkkkk____CCCCrrrreeeeaaaatttteeeeWWWWiiiinnnnddddoooowwww, the parent of the new window must exist at the
  177.      time of the call, but the new window must not already exist.
  178.  
  179.      In truth, the window-creation procedures don't actually issue the command
  180.      to X to create a window.  Instead, they create a local data structure
  181.      associated with the window and defer the creation of the X window.  The
  182.      window will actually be created by the first call to TTTTkkkk____MMMMaaaappppWWWWiiiinnnnddddoooowwww.
  183.      Deferred window creation allows various aspects of the window (such as
  184.      its size, background color, etc.) to be modified after its creation
  185.      without incurring any overhead in the X server.  When the window is
  186.      finally mapped all of the window attributes can be set while creating the
  187.      window.
  188.  
  189.      The value returned by a window-creation procedure is not the X token for
  190.      the window (it can't be, since X hasn't been asked to create the window
  191.      yet).  Instead, it is a token for Tk's local data structure for the
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. TTTTkkkk____CCCCrrrreeeeaaaatttteeeeMMMMaaaaiiiinnnnWWWWiiiinnnnddddoooowwww((((3333TTTTkkkk))))                              TTTTkkkk____CCCCrrrreeeeaaaatttteeeeMMMMaaaaiiiinnnnWWWWiiiinnnnddddoooowwww((((3333TTTTkkkk))))
  203.  
  204.  
  205.  
  206.      window.  Most of the Tk library procedures take Tk_Window tokens, rather
  207.      than X identifiers.  The actual X window identifier can be retrieved from
  208.      the local data structure using the TTTTkkkk____WWWWiiiinnnnddddoooowwwwIIIIdddd macro;  see the manual
  209.      entry for TTTTkkkk____WWWWiiiinnnnddddoooowwwwIIIIdddd for details.
  210.  
  211.      TTTTkkkk____DDDDeeeessssttttrrrrooooyyyyWWWWiiiinnnnddddoooowwww deletes a window and all the data structures associated
  212.      with it, including any event handlers created with TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEEvvvveeeennnnttttHHHHaaaannnnddddlllleeeerrrr.
  213.      In addition, TTTTkkkk____DDDDeeeessssttttrrrrooooyyyyWWWWiiiinnnnddddoooowwww will delete any children of _t_k_w_i_n
  214.      recursively (where children are defined in the Tk sense, consisting of
  215.      all windows that were created with the given window as _p_a_r_e_n_t).  If _t_k_w_i_n
  216.      was created by TTTTkkkk____CCCCrrrreeeeaaaatttteeeeIIIInnnntttteeeerrrrnnnnaaaallllWWWWiiiinnnnddddoooowwww then event handlers interested in
  217.      destroy events are invoked immediately.  If _t_k_w_i_n is a top-level or main
  218.      window, then the event handlers will be invoked later, after X has seen
  219.      the request and returned an event for it.
  220.  
  221.      If a window has been created but hasn't been mapped, so no X window
  222.      exists, it is possible to force the creation of the X window by calling
  223.      TTTTkkkk____MMMMaaaakkkkeeeeWWWWiiiinnnnddddoooowwwwEEEExxxxiiiisssstttt.  This procedure issues the X commands to instantiate
  224.      the window given by _t_k_w_i_n.
  225.  
  226.  
  227. KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  228.      create, deferred creation, destroy, display, internal window, main
  229.      window, register, screen, top-level window, window
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.